.TH std::ranges::views::iota,std::ranges::iota_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::ranges::views::iota,std::ranges::iota_view \- std::ranges::views::iota,std::ranges::iota_view

.SH Synopsis
   Defined in header <ranges>
   template< std::weakly_incrementable W,

             std::semiregular Bound = std::unreachable_sentinel_t >
       requires __WeaklyEqualityComparableWith<W, Bound> &&           \fB(1)\fP \fI(since C++20)\fP
   std::copyable<W>
   class iota_view

       : public ranges::view_interface<iota_view<W, Bound>>
   namespace views {

       inline constexpr /* unspecified */ iota = /* unspecified */;   \fB(2)\fP \fI(since C++20)\fP

   }
   Call signature
   template< class W >

       requires /* see below */                                           \fI(since C++20)\fP

   constexpr /* see below */ iota( W&& value );
   template< class W, class Bound >

       requires /* see below */                                           \fI(since C++20)\fP

   constexpr /* see below */ iota( W&& value, Bound&& bound );

   1) A range factory that generates a sequence of elements by repeatedly incrementing
   an initial value. Can be either bounded or unbounded (infinite).
   2) views::iota(e) and views::iota(e, f) are expression-equivalent to iota_view(e)
   and iota_view(e, f) respectively for any suitable subexpressions e and f.

.SH Member functions

   constructor   creates an iota_view
   (C++20)       \fI(public member function)\fP
   begin         obtains the beginning iterator of an iota_view
   (C++20)       \fI(public member function)\fP
   end           obtains the sentinel denoting the end of an iota_view
   (C++20)       \fI(public member function)\fP
   empty         tests whether the iota_view is empty, i.e. the iterator and the
   (C++20)       sentinel compare equal
                 \fI(public member function)\fP
   size          obtains the size of an iota_view if it is sized
   (C++20)       \fI(public member function)\fP
         Inherited from std::ranges::view_interface
   cbegin        returns a constant iterator to the beginning of the range.
   (C++23)       \fI(public member function of std::ranges::view_interface<D>)\fP
   cend          returns a sentinel for the constant iterator of the range.
   (C++23)       \fI(public member function of std::ranges::view_interface<D>)\fP
   operator bool returns whether the derived view is not empty. Provided if
   (C++20)       ranges::empty is applicable to it.
                 \fI(public member function of std::ranges::view_interface<D>)\fP
   front         returns the first element in the derived view. Provided if it
   (C++20)       satisfies forward_range.
                 \fI(public member function of std::ranges::view_interface<D>)\fP
   back          returns the last element in the derived view. Provided if it satisfies
   (C++20)       bidirectional_range and common_range.
                 \fI(public member function of std::ranges::view_interface<D>)\fP
   operator[]    returns the n^th element in the derived view. Provided if it satisfies
   (C++20)       random_access_range.
                 \fI(public member function of std::ranges::view_interface<D>)\fP

std::ranges::iota_view::iota_view

   iota_view() requires std::default_initializable<W> = default;      \fB(1)\fP \fI(since C++20)\fP
   constexpr explicit iota_view( W value );                           \fB(2)\fP \fI(since C++20)\fP
   constexpr explicit iota_view( std::type_identity_t<W> value,       \fB(3)\fP \fI(since C++20)\fP
                                 std::type_identity_t<Bound> bound );
   constexpr explicit iota_view( /* iterator */ first, /* see below   \fB(4)\fP \fI(since C++20)\fP
   */ last );

   1) Value-initializes value_ and bound_ via their default member initializers (= W()
   and = Bound()).
   2) Initializes value_ with value and value-initializes bound_. This constructor is
   used to create unbounded iota_views, e.g. iota\fB(0)\fP yields numbers 0,1,2...,
   infinitely.
   3) Initializes value_ with value and bound_ with bound. The behavior is undefined if
   std::totally_ordered_with<W, Bound> is modeled and bool(value <= bound) is false.
   This constructor is used to create bounded iota views, e.g. iota(10, 20) yields
   numbers from 10 to 19.
   4) Same as \fB(3)\fP, except that value_ is initialized with the W value stored in first,
   and
     * if W and Bound are the same type, then the type of last is /* iterator */ and
       bound_ initialized with the W value stored in last,
     * otherwise, if the iota_view is unbounded (i.e. Bound is
       std::unreachable_sentinel_t), then the type of last is
       std::unreachable_sentinel_t and bound_ initialized with
       std::unreachable_sentinel.
     * otherwise, the type of last is /* sentinel */ and bound_ initialized with the
       Bound value stored in last.
   In any case, the type of last is same as decltype(end()).

   For \fB(2)\fP, \fB(3)\fP, and \fB(4)\fP, the behavior is undefined if the iota_view is bounded (i.e.
   Bound is not std::unreachable_sentinel_t) and bound_ is initialized to a value
   unreachable from value_.

.SH Parameters

   value - the starting value
   bound - the bound
   first - the iterator denoting the starting value
   last  - the iterator or sentinel denoting the bound

std::ranges::iota_view::begin

   constexpr /* iterator */ begin() const;  \fI(since C++20)\fP

   Returns an iterator initialized with value_.

std::ranges::iota_view::end

   constexpr auto end() const;                                        \fB(1)\fP \fI(since C++20)\fP
   constexpr /* iterator */ end() const requires std::same_as<W,      \fB(2)\fP \fI(since C++20)\fP
   Bound>;

   1) Returns a sentinel of a specific type (shown as /* sentinel */ here) initialized
   with bound_ if this view is bounded, or std::unreachable_sentinel if this view is
   unbounded.
   2) Returns an iterator initialized with bound_.

std::ranges::iota_view::empty

   constexpr bool empty() const;  \fI(since C++20)\fP

   Equivalent to return value_ == bound_;.

std::ranges::iota_view::size

   constexpr auto size() const

       requires (std::same_as<W, Bound> && /* advanceable */<W>)
           || (/* is-integer-like */<W> && /* is-integer-like */<Bound>)
           || std::sized_sentinel_for<Bound, W>
   {
       if constexpr (/* is-integer-like */<W> && /* is-integer-like
   */<Bound>)
           return (value_ < 0)
               ? ((bound_ < 0)                                            \fI(since C++20)\fP
                   ? /* to-unsigned-like */(-value_)
                       - /* to-unsigned-like */(-bound_)
                   : /* to-unsigned-like */(bound_)
                       + /* to-unsigned-like */(-value_))
               : /* to-unsigned-like */(bound_) - /* to-unsigned-like
   */(value_);
       else
           return /* to-unsigned-like */(bound_ - value_);

   }

   Returns the size of the view if the view is bounded.

   The exposition-only concept advanceable is described in this page.

   The exposition-only function template to-unsigned-like converts its argument (which
   must be integer-like) to the corresponding unsigned version of the argument type.

   Deduction guides

   template< class W, class Bound >

       requires (!/* is-integer-like */<W>
           || !/* is-integer-like */<Bound>             \fI(since C++20)\fP
           || /* is-signed-integer-like */<W>
               == /* is-signed-integer-like */<Bound>)

     iota_view( W, Bound ) -> iota_view<W, Bound>;

   For any type T, /* is-integer-like */<T> is true if and only if T is integer-like,
   and /* is-signed-integer-like */<T> is true if and only if T is integer-like and
   capable of representing negative values.

   Note that the guide protects itself against signed/unsigned mismatch bugs, like
   views::iota(0, v.size()), where 0 is a (signed) int and v.size() is an (unsigned)
   std::size_t.

   Nested classes

   iterator the iterator type
   (C++20)  (exposition-only member class*)
   sentinel the sentinel type used when the iota_view is bounded and Bound and W are
   (C++20)  not the same type
            (exposition-only member class*)

   Helper templates

   template< std::weakly_incrementable W, std::semiregular Bound >
   inline constexpr bool enable_borrowed_range<ranges::iota_view<W,       \fI(since C++20)\fP
   Bound>> = true;

   This specialization of std::ranges::enable_borrowed_range makes iota_view satisfy
   borrowed_range.

.SH Example


// Run this code

 #include <algorithm>
 #include <iostream>
 #include <ranges>

 struct Bound
 {
     int bound;
     bool operator==(int x) const { return x == bound; }
 };

 int main()
 {
     for (int i : std::ranges::iota_view{1, 10})
         std::cout << i << ' ';
     std::cout << '\\n';

     for (int i : std::views::iota(1, 10))
         std::cout << i << ' ';
     std::cout << '\\n';

     for (int i : std::views::iota(1, Bound{10}))
         std::cout << i << ' ';
     std::cout << '\\n';

     for (int i : std::views::iota(1) | std::views::take(9))
         std::cout << i << ' ';
     std::cout << '\\n';

     std::ranges::for_each(std::views::iota(1, 10), [](int i)
     {
         std::cout << i << ' ';
     });
     std::cout << '\\n';
 }

.SH Output:

 1 2 3 4 5 6 7 8 9
 1 2 3 4 5 6 7 8 9
 1 2 3 4 5 6 7 8 9
 1 2 3 4 5 6 7 8 9
 1 2 3 4 5 6 7 8 9

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to            Behavior as published              Correct behavior
   LWG 3523 C++20      iterator-sentinel pair constructor might    corrected
                       use wrong sentinel type
   LWG 3610 C++20      size might reject integer-class types       accept if possible
   LWG 4001 C++20      the inherited member empty function was not empty is always
                       always valid                                provided
   P2325R3  C++20      iota_view required that W is semiregular    only requires that W
                       as view required default_initializable      is copyable
   P2711R1  C++20      the multi-parameter constructors were not   made explicit
                       explicit

.SH See also

   iota                fills a range with successive increments of the starting value
   \fI(C++11)\fP             \fI(function template)\fP
   ranges::iota        fills a range with successive increments of the starting value
   (C++23)             (niebloid)
   ranges::repeat_view a view consisting of a generated sequence by repeatedly
   views::repeat       producing the same value
   (C++23)             \fI(class template)\fP (customization point object)
